home *** CD-ROM | disk | FTP | other *** search
/ MacHack 2001 / MacHack 2001.toast / pc / The Hacks / pseudoDoc / headerDoc2HTML.pl < prev    next >
Encoding:
Perl Script  |  2001-06-23  |  29.3 KB  |  742 lines
  1. #!/usr/bin/perl
  2. #
  3. # Script name: headerDoc2HTML
  4. # Synopsis: Scans a file for headerDoc comments and generates an HTML
  5. #           file from the comments it finds.
  6. #
  7. # Author: Matt Morse (matt@apple.com)
  8. # Last Updated: $Date: 2001/06/06 18:02:45 $
  9. #
  10. # Copyright (c) 1999 Apple Computer, Inc.  All Rights Reserved.
  11. # The contents of this file constitute Original Code as defined in and are
  12. # subject to the Apple Public Source License Version 1.1 (the "License").
  13. # You may not use this file except in compliance with the License.  Please
  14. # obtain a copy of the License at http://www.apple.com/publicsource and
  15. # read it before using this file.
  16. #
  17. # This Original Code and all software distributed under the License are
  18. # distributed on an AS IS basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  19. # EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  20. # INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS
  21. # FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the License for
  22. # the specific language governing rights and limitations under the
  23. # License.
  24. #
  25. # $Revision: 1.21 $
  26. #####################################################################
  27.  
  28. my $VERSION = 2.1;
  29. ################ General Constants ###################################
  30. my $isMacOS;
  31. my $pathSeparator;
  32. my $specifiedOutputDir;
  33. my $export;
  34. my $debugging;
  35. my $testingExport = 0;
  36. my $printVersion;
  37. #################### Locations #####################################
  38. # Look-up tables are used when exporting API and doc to tab-delimited
  39. # data files, which can be used for import to a database.  
  40. # The look-up tables supply uniqueID-to-APIName mappings.
  41.  
  42. my $scriptDir;
  43. my $lookupTableDirName;
  44. my $lookupTableDir;
  45. my $dbLookupTables;
  46. my $functionFilename;
  47. my $typesFilename;
  48. my $enumsFilename;
  49. my $masterTOCName;
  50. my @inputFiles;
  51.  
  52. # Check options in BEGIN block to avoid overhead of loading supporting 
  53. # modules in error cases.
  54. BEGIN {
  55.     use Cwd;
  56.     use Getopt::Std;
  57.     use File::Find;
  58.     
  59.     my %options = ();
  60.     $lookupTableDirName = "LookupTables";
  61.     $functionFilename = "functions.tab";;
  62.     $typesFilename = "types.tab";
  63.     $enumsFilename = "enumConstants.tab";
  64.  
  65.     $scriptDir = cwd();
  66.  
  67.     if ($^O =~ /MacOS/i) {
  68.             $pathSeparator = ":";
  69.             $isMacOS = 1;
  70.     } else {
  71.             $pathSeparator = "/";
  72.             $isMacOS = 0;
  73.     }
  74.     foreach (qw(Mac::Files)) {
  75.         $MOD_AVAIL{$_} = eval "use $_; 1";
  76.     }
  77.  
  78.     &getopts("dvxo:", \%options);
  79.     if ($options{v}) {
  80.         print "Getting version information for all modules.  Please wait...\n";
  81.         $printVersion = 1;
  82.         return;
  83.     }
  84.  
  85.     if ($options{d}) {
  86.             print "\tDebugging on...\n\n";
  87.             $debugging = 1;
  88.     }
  89.  
  90.     if ($options{o}) {
  91.         $specifiedOutputDir = $options{o};
  92.         if (! -e $specifiedOutputDir)  {
  93.             unless (mkdir ("$specifiedOutputDir", 0777)) {
  94.                 die "Error: $specifiedOutputDir does not exist. Exiting. \n$!\n";
  95.             }
  96.         } elsif (! -d $specifiedOutputDir) {
  97.             die "Error: $specifiedOutputDir is not a directory. Exiting.\n$!\n";
  98.         } elsif (! -w $specifiedOutputDir) {
  99.             die "Error: Output directory $specifiedOutputDir is not writable. Exiting.\n$!\n";
  100.         }
  101.         print "\nDocumentation will be written to $specifiedOutputDir\n";
  102.     }
  103.     $lookupTableDir = "$scriptDir$pathSeparator$lookupTableDirName";
  104.     if (($options{x}) || ($testingExport)) {
  105.         if ((-e "$lookupTableDir$pathSeparator$functionFilename") && (-e "$lookupTableDir$pathSeparator$typesFilename")) {
  106.                 print "\nWill write database files to an Export directory within each top-level HTML directory.\n\n";
  107.                 $export = 1;
  108.         } else {
  109.                 print "\nLookup table files not available. Cannot export data.\n";
  110.             $export = 0;
  111.                 $testingExport = 0;
  112.         }
  113.     }
  114.     
  115.     if (($#ARGV == 0) && (-d $ARGV[0])) {
  116.         my $inputDir = $ARGV[0];
  117.         $inputDir =~ s|(.*)/$|$1|; # get rid of trailing slash, if any
  118.         &find({wanted => \&getHeaders, follow => 1}, $inputDir);
  119.     } else {
  120.         print "Will process one or more individual files.\n" if ($debugging);
  121.         foreach my $singleFile (@ARGV) {
  122.             if (-f $singleFile) {
  123.                     push(@inputFiles, $singleFile);
  124.                 }
  125.         }
  126.     }
  127.     unless (@inputFiles) {
  128.         print "No valid input files specified. \n\n";
  129.         if ($isMacOS) {
  130.             die "\tTo use HeaderDoc, drop a header file or folder of header files on this application.\n\n";
  131.             } else {
  132.                     die "\tUsage: headerDoc2HTML [-d] [-o <output directory>] <input file(s) or directory>.\n\n";
  133.             }
  134.     }
  135.     
  136.     sub getHeaders {
  137.         my $filePath = $File::Find::name;
  138.         my $fileName = $_;
  139.         
  140.         if ($fileName =~ /\.h$/) {
  141.             push(@inputFiles, $filePath);
  142.         }
  143.     }
  144. }
  145.  
  146.  
  147. use strict;
  148. use File::Copy;
  149. use FindBin qw ($Bin);
  150. use lib "$Bin". "$pathSeparator"."Modules";
  151.  
  152. # Classes and other modules specific to HeaderDoc
  153. use HeaderDoc::DBLookup;
  154. use HeaderDoc::Utilities qw(findRelativePath safeName getAPINameAndDisc printArray printHash updateHashFromConfigFiles getHashFromConfigFile);
  155. use HeaderDoc::Header;
  156. use HeaderDoc::CPPClass;
  157. use HeaderDoc::ObjCClass;
  158. use HeaderDoc::Function;
  159. use HeaderDoc::Typedef;
  160. use HeaderDoc::Struct;
  161. use HeaderDoc::Constant;
  162. use HeaderDoc::Var;
  163. use HeaderDoc::PDefine;
  164. use HeaderDoc::Enum;
  165. use HeaderDoc::MinorAPIElement;
  166.  
  167. ################ Setup from Configuration File #######################
  168. my $localConfigFileName = "headerDoc2HTML.config";
  169. my $preferencesConfigFileName = "com.apple.headerDoc2HTML.config";
  170. my $homeDir = (getpwuid($<))[7];
  171. my $usersPreferencesPath = $homeDir.$pathSeparator."Library".$pathSeparator."Preferences";
  172.  
  173. # The order of files in this array determines the order that the config files will be read
  174. # If there are multiple config files that declare a value for the same key, the last one read wins
  175. my @configFiles = ($usersPreferencesPath.$pathSeparator.$preferencesConfigFileName, $Bin.$pathSeparator.$localConfigFileName);
  176.  
  177. # default configuration, which will be modified by assignments found in config files.
  178. my %config = (
  179.     copyrightOwner => "",
  180.     defaultFrameName => "index.html",
  181.     compositePageName => "CompositePage.html",
  182.     masterTOCName => "MasterTOC.html",
  183.     apiUIDPrefix => "apple_ref"
  184. );
  185.  
  186. %config = &updateHashFromConfigFiles(\%config,\@configFiles);
  187.  
  188. if (defined $config{"copyrightOwner"}) {
  189.     HeaderDoc::APIOwner->copyrightOwner($config{"copyrightOwner"});
  190. }
  191. if (defined $config{"defaultFrameName"}) {
  192.     HeaderDoc::APIOwner->defaultFrameName($config{"defaultFrameName"});
  193. }
  194. if (defined $config{"compositePageName"}) {
  195.     HeaderDoc::APIOwner->compositePageName($config{"compositePageName"});
  196. }
  197. if (defined $config{"apiUIDPrefix"}) {
  198.     HeaderDoc::APIOwner->apiUIDPrefix($config{"apiUIDPrefix"});
  199. }
  200.  
  201. ################ Version Info ##############################
  202. if ($printVersion) {
  203.     &printVersionInfo();
  204.     exit;
  205. } 
  206.  
  207. ################ Exporting ##############################
  208. if ($export || $testingExport) {
  209.     HeaderDoc::DBLookup->loadUsingFolderAndFiles($lookupTableDir, $functionFilename, $typesFilename, $enumsFilename);
  210. }
  211.  
  212. ################### States ###########################################
  213. my $inHeader = 0;
  214. my $inCPPHeader = 0;
  215. my $inClass = 0;
  216. my $inFunction = 0;
  217. my $inTypedef = 0;
  218. my $inStruct = 0;
  219. my $inConstant = 0;
  220. my $inVar = 0;
  221. my $inPDefine = 0;
  222. my $inEnum = 0;
  223.  
  224. ################ Processing starts here ##############################
  225. my $headerObject;  # this is the Header object that will own the HeaderElement objects for this file.
  226.  
  227. foreach my $inputFile (@inputFiles) {
  228.     my $constantObj;
  229.     my $enumObj;
  230.     my $funcObj;
  231.     my $pDefineObj;
  232.     my $structObj;
  233.     my $typedefObj;
  234.     my $varObj;
  235.     my $cppAccessControlState = "protected:"; # the default in C++
  236.     
  237.     my @path = split (/$pathSeparator/, $inputFile);
  238.     my $filename = pop (@path);
  239.     print "\nProcessing $filename\n";
  240.     
  241.     my $headerDir = join("$pathSeparator", @path);
  242.     my $rootFileName;
  243.     ($rootFileName = $filename) =~ s/\.(h|i)$//;
  244.     my $rootOutputDir;
  245.     if (length ($specifiedOutputDir)) {
  246.         $rootOutputDir ="$specifiedOutputDir$pathSeparator$rootFileName";
  247.     } elsif (@path) {
  248.         $rootOutputDir ="$headerDir$pathSeparator$rootFileName";
  249.     } else {
  250.         $rootOutputDir = $rootFileName;
  251.     }
  252.         
  253.     open(INPUTFILE, "<$inputFile") || die "Can't open input file $inputFile.\n$!\n";
  254.     my @rawInputLines = <INPUTFILE>;
  255.     close INPUTFILE;
  256.     
  257.     # check for HeaderDoc comments -- if none, move to next file
  258.     my @headerDocCommentLines = grep(/^\s*\/\*\!/, @rawInputLines);
  259.     if (!@headerDocCommentLines) {
  260.         print "    Skipping. No HeaderDoc comments found.\n";
  261.         next;
  262.     }
  263.     
  264.     $headerObject = HeaderDoc::Header->new();
  265.     $headerObject->outputDir($rootOutputDir);
  266.     $headerObject->name($filename);
  267.     
  268.     # scan input lines for class declarations
  269.     # return an array of array refs, the first array being the header-wide lines
  270.     # the others (if any) being the class-specific lines
  271.     my @lineArrays = &getLineArrays(\@rawInputLines);
  272.     
  273.     foreach my $arrayRef (@lineArrays) {
  274.         my @inputLines = @$arrayRef; 
  275.         # look for /*! comments and collect all comment fields into a the appropriate objects
  276.         my $apiOwner = $headerObject;  # switches to a class object, when within a class declaration
  277.         my $inputCounter = 0;
  278.         while ($inputCounter <= $#inputLines) {
  279.             my $localDebug = 0;
  280.             my $line = "";           
  281.             
  282.             print "Input line number: $inputCounter\n" if ($localDebug);
  283.             if ($inputLines[$inputCounter] =~ /^\s*(public:|private:|protected:)/) {$cppAccessControlState = $&;}
  284.             if ($inputLines[$inputCounter] =~ /^\s*\/\*\!/) {  # entering headerDoc comment
  285.                 # slurp up comment as line
  286.                 if ($inputLines[$inputCounter] =~ /\s*\*\//) { # closing comment marker on same line
  287.                     $line .= $inputLines[$inputCounter++];
  288.                     print "Input line number: $inputCounter\n" if ($localDebug);
  289.                 } else {                                       # multi-line comment
  290.                     do {
  291.                         $inputLines[$inputCounter] =~ s/^[\t ]*[*]?[\t ]+(.*)$/$1/; # remove leading whitespace, and any leading asterisks
  292.                         $line .= $inputLines[$inputCounter++];
  293.                         print "Input line number: $inputCounter\n" if ($localDebug);
  294.                     } while (($inputLines[$inputCounter] !~ /\*\//) && ($inputCounter <= $#inputLines));
  295.                     $line .= $inputLines[$inputCounter++];     # get the closing comment marker
  296.                     print "Input line number: $inputCounter\n" if ($localDebug);
  297.                 }
  298.                 $line =~ s/^\s+//;              # trim leading whitespace
  299.                 $line =~ s/^(.*)\*\/\s*$/$1/s;  # remove closing comment marker
  300.                
  301.                SWITCH: { # determine which type of comment we're in
  302.                     ($line =~ /^\/\*!\s+\@header\s*/i) && do {$inHeader = 1; last SWITCH;};
  303.                     ($line =~ /^\/\*!\s+\@class\s*/i) && do {$inClass = 1;last SWITCH;};
  304.                      ($line =~ /^\/\*!\s+\@language\s+.*c\+\+\s*/i) && do {$inCPPHeader = 1; last SWITCH;};
  305.                     ($line =~ /^\/\*!\s+\@function\s*/i) && do {$inFunction = 1;last SWITCH;};
  306.                     ($line =~ /^\/\*!\s+\@typedef\s*/i) && do {$inTypedef = 1;last SWITCH;};
  307.                     ($line =~ /^\/\*!\s+\@struct\s*/i) && do {$inStruct = 1;last SWITCH;};
  308.                     ($line =~ /^\/\*!\s+\@const(ant)?\s*/i) && do {$inConstant = 1;last SWITCH;};
  309.                     ($line =~ /^\/\*!\s+\@var\s*/i) && do {$inVar = 1;last SWITCH;};
  310.                     ($line =~ /^\/\*!\s+\@define(d)?\s*/i) && do {$inPDefine = 1;last SWITCH;};
  311.                     ($line =~ /^\/\*!\s+\@enum\s*/i) && do {$inEnum = 1;last SWITCH;};
  312.                     print "HeaderDoc comment is not of known type. Comment text is:\n";
  313.                     print "$line\n";
  314.                }
  315.                 $line =~ s/\n\n/\n<br><br>\n/g; # change newline pairs into HTML breaks, for para formatting
  316.                 my @fields = split(/\@/, $line);
  317.                 if ($inCPPHeader) {print "inCPPHeader\n" if ($debugging); &processCPPHeaderComment();};
  318.                 if ($inClass) {print "inClass\n" if ($debugging); $apiOwner = &processClassComment($apiOwner, $rootOutputDir, \@fields);};
  319.                 if ($inHeader) {print "inHeader\n" if ($debugging); $apiOwner = &processHeaderComment($apiOwner, $rootOutputDir, \@fields);};
  320.                 if ($inFunction) {
  321.                     print "inFunction\n" if ($localDebug);
  322.                     $funcObj = HeaderDoc::Function->new;
  323.                     $funcObj->processFunctionComment(\@fields);
  324.                      while (($inputLines[$inputCounter] !~ /\w/)  && ($inputCounter <= $#inputLines)){ 
  325.                          $inputCounter++;
  326.                          print "Input line number: $inputCounter\n" if ($localDebug);
  327.                     }; # move beyond blank lines
  328.                     
  329.                     if ($inputLines[$inputCounter] =~ /^#define/) { # if function-like macro
  330.                         my $declaration = $inputLines[$inputCounter];
  331.                         while (($declaration =~ /\\\n$/)  && ($inputCounter <= $#inputLines)){ 
  332.                             $inputCounter++;
  333.                             $declaration .= $inputLines[$inputCounter];
  334.                             print "Input line number: $inputCounter\n" if ($localDebug);
  335.                         }; # get escaped-newline lines
  336.                         $funcObj->setFunctionDeclaration($declaration);
  337.                     } else { # if regular function
  338.                         my $declaration = $inputLines[$inputCounter];
  339.                         if ($declaration !~ /;[^;]*$/) { # search for semicolon end, even with trailing comment
  340.                             do { 
  341.                                 $inputCounter++;
  342.                                 print "Input line number: $inputCounter\n" if ($localDebug);
  343.                                 $declaration .= $inputLines[$inputCounter];
  344.                             } while (($declaration !~ /;[^;]*$/)  && ($inputCounter <= $#inputLines))
  345.                         }
  346.                         $declaration =~ s/^\s+//g;                # trim leading spaces.
  347.                         $declaration =~ s/([^;]*;).*$/$1/s;        # trim anything following the final semicolon, 
  348.                                                                 # including comments.
  349.                         $declaration =~ s/([^{]+){.*;$/$1;/s;   # handle inline functions [#2423551]
  350.                                                                 # by removing opening brace up to semicolon
  351.                         $declaration =~ s/\s+;/;/;                # trim spaces before semicolon.
  352.                         if ($declaration =~ /^virtual.*/) {
  353.                             $funcObj->linkageState("virtual");
  354.                         } elsif ($declaration =~ /^static.*/) {
  355.                             $funcObj->linkageState("static");
  356.                         } else {
  357.                             $funcObj->linkageState("other");
  358.                         }
  359.                         $funcObj->setFunctionDeclaration($declaration);
  360.                     }
  361.                     if (length($funcObj->name())) {
  362.                         if (ref($apiOwner) ne "HeaderDoc::Header") {
  363.                             $funcObj->accessControl($cppAccessControlState);
  364.                         }
  365.                         $apiOwner->addToFunctions($funcObj);
  366.                     }
  367.                 }
  368.                 if ($inTypedef) {
  369.                     $typedefObj = HeaderDoc::Typedef->new;
  370.                     $typedefObj->processTypedefComment(\@fields);
  371.                     my $typedefName = $typedefObj->name();
  372.                     
  373.                      while (($inputLines[$inputCounter] !~ /\w/)  && ($inputCounter <= $#inputLines)){
  374.                          $inputCounter++;
  375.                         print "Input line number: $inputCounter\n" if ($localDebug);
  376.                      };
  377.                     my  $declaration = $inputLines[$inputCounter];
  378.                     # if a struct declaration precedes the typedef, suck it up
  379.                     if ($declaration !~ /typedef/) {
  380.                         while (($inputLines[$inputCounter] !~ /typedef/) && ($inputCounter <= $#inputLines)){
  381.                             $declaration .= $inputLines[++$inputCounter];
  382.                             print "Input line number: $inputCounter\n" if ($localDebug);
  383.                         };
  384.                     } else {
  385.                         if ($declaration =~ /{/) { # taking care of a typedef'd block
  386.                             while (($inputLines[$inputCounter] !~ /}/) && ($inputCounter <= $#inputLines)) {$declaration .= $inputLines[++$inputCounter]; print "Input line number: $inputCounter\n" if ($localDebug);};
  387.                         } else {
  388.                             if ($declaration !~ /$typedefName/) { # find type name at end of declaration
  389.                                 while (($inputLines[$inputCounter] !~ /$typedefName/) && ($inputCounter <= $#inputLines)){
  390.                                     $declaration .= $inputLines[++$inputCounter]; 
  391.                                     print "Input line number: $inputCounter\n" if ($localDebug);
  392.                                 }
  393.                             } else { # find final semicolon
  394.                                 while (($inputLines[$inputCounter] !~ /;/) && ($inputCounter <= $#inputLines)){
  395.                                     $declaration .= $inputLines[++$inputCounter]; 
  396.                                     print "Input line number: $inputCounter\n" if ($localDebug);
  397.                                 }
  398.                             }
  399.                         }
  400.                     }
  401.                     if (length($declaration)) {
  402.                         $typedefObj->setTypedefDeclaration($declaration);
  403.                     } else {
  404.                         warn "Couldn't find a declaration for typedef near line: $inputCounter\n";
  405.                     }
  406.                     if (length($typedefObj->name())) {
  407.                         if (ref($apiOwner) ne "HeaderDoc::Header") {
  408.                             $typedefObj->accessControl($cppAccessControlState);
  409.                             $apiOwner->addToVars($typedefObj);
  410.                         } else { # headers group by type
  411.                             $apiOwner->addToTypedefs($typedefObj);
  412.                         }
  413.                     }
  414.                 }  ## end inTypedef
  415.                 
  416.                 if ($inStruct) { 
  417.                     $structObj = HeaderDoc::Struct->new;
  418.                     $structObj->processStructComment(\@fields);
  419.                      while (($inputLines[$inputCounter] !~ /\w/)  && ($inputCounter <= $#inputLines)){ $inputCounter++; print "Input line number: $inputCounter\n" if ($localDebug);}; # move beyond blank lines
  420.                     my  $declaration = $inputLines[$inputCounter];
  421.                     while ($inputLines[$inputCounter] !~ /}/) {$declaration .= $inputLines[++$inputCounter]; print "Input line number: $inputCounter\n" if ($localDebug);}; # simplistic
  422.                     if (length($declaration)) {
  423.                         $structObj->setStructDeclaration($declaration);
  424.                     } else {
  425.                         warn "Couldn't find a declaration for struct near line: $inputCounter\n";
  426.                     }
  427.                     if (length($structObj->name())) {
  428.                         if (ref($apiOwner) ne "HeaderDoc::Header") {
  429.                             $structObj->accessControl($cppAccessControlState);
  430.                             $apiOwner->addToVars($structObj);
  431.                         } else { # headers group by type
  432.                             $apiOwner->addToStructs($structObj);
  433.                         }
  434.                     }
  435.                 }  ## end inStruct
  436.                           
  437.                 if ($inConstant) {
  438.                     $constantObj = HeaderDoc::Constant->new;
  439.                     $constantObj->processConstantComment(\@fields);
  440.                     while (($inputLines[$inputCounter] !~ /\w/)  && ($inputCounter <= $#inputLines)){$inputCounter++; print "Input line number: $inputCounter\n" if ($localDebug);};
  441.                     if ($inputLines[$inputCounter] =~ /^\s*(const|extern|CF_EXPORT)/) {
  442.                        my $declaration = $inputLines[$inputCounter];
  443.                        if ($declaration !~ /;\s*$/) {
  444.                            $inputCounter++;
  445.                            print "Input line number: $inputCounter\n" if ($localDebug);
  446.                            while (($declaration !~ /\s*;\s*$/) && ($inputCounter <= $#inputLines)){$declaration .= $inputLines[$inputCounter++];print "Input line number: $inputCounter\n" if ($localDebug);};
  447.                        }
  448.                        $declaration =~ s/CF_EXPORT\s+//;
  449.                        $constantObj->setConstantDeclaration($declaration);
  450.                     }
  451.                     if (length($constantObj->name())) {
  452.                         if (ref($apiOwner) ne "HeaderDoc::Header") {
  453.                             $constantObj->accessControl($cppAccessControlState);
  454.                             $apiOwner->addToVars($constantObj);
  455.                         } else { # headers group by type
  456.                             $apiOwner->addToConstants($constantObj);
  457.                         }
  458.                     }
  459.                 } ## end inConstant
  460.                 
  461.                 if ($inVar) {
  462.                     $varObj = HeaderDoc::Var->new;
  463.                     $varObj->processVarComment(\@fields);
  464.                     while (($inputLines[$inputCounter] !~ /\w/)  && ($inputCounter <= $#inputLines)){  $inputCounter++; print "Input line number: $inputCounter\n" if ($localDebug);};
  465.                     my $declaration = &removeSlashSlashComment($inputLines[$inputCounter]);
  466.                     if ($declaration !~ /;\s*$/) {
  467.                         $inputCounter++;
  468.                         print "Input line number: $inputCounter\n" if ($localDebug);
  469.                         while (($declaration !~ /}\s*;\s*$/)  && ($inputCounter <= $#inputLines)){$declaration .= &removeSlashSlashComment($inputLines[$inputCounter++]); print "Input line number: $inputCounter\n" if ($localDebug);};
  470.                     }
  471.                     $varObj->setVarDeclaration($declaration);
  472.                     if (length($varObj->name())) {
  473.                         if (ref($apiOwner) ne "HeaderDoc::Header") {
  474.                             $varObj->accessControl($cppAccessControlState);
  475.                             $apiOwner->addToVars($varObj);
  476.                         } else { # headers group by type
  477.                             warn "### \@var tag found outside of a class declaration. \n";
  478.                             $varObj->printObject();
  479.                             $apiOwner->addToVars($varObj);  # we add it anyway
  480.                         }
  481.                     }
  482.                 } ## end inVar
  483.                 
  484.                 if ($inPDefine) {
  485.                     $pDefineObj = HeaderDoc::PDefine->new;
  486.                     $pDefineObj->processPDefineComment(\@fields);
  487.                     while (($inputLines[$inputCounter] !~ /\w/) && ($inputCounter <= $#inputLines)){  $inputCounter++;print "Input line number: $inputCounter\n" if ($localDebug);};
  488.                     my $declaration;
  489.                     if ($inputLines[$inputCounter] =~ /^\s*#define/) {
  490.                         while (($inputLines[$inputCounter] =~ /^\s*#define/) && ($inputCounter <= $#inputLines)){
  491.                             $declaration .= $inputLines[$inputCounter];
  492.                             if ($declaration =~ /\\\n$/) {  # escaped newlines
  493.                                 while (($declaration =~ /\\\n$/) && ($inputCounter <= $#inputLines)){$inputCounter++; $declaration .= $inputLines[$inputCounter];print "Input line number: $inputCounter\n" if ($localDebug);};
  494.                             }
  495.                             $inputCounter++;
  496.                             print "Input line number: $inputCounter\n" if ($localDebug);
  497.                         }
  498.                     } else { 
  499.                         warn "Can't find declaration for \@define comment with name:\n";
  500.                         my $name = $pDefineObj->name();
  501.                         print "$name\n\n";
  502.                     }
  503.                     $pDefineObj->setPDefineDeclaration($declaration);
  504.                     
  505.                     if (length($pDefineObj->name())) {
  506.                         if (ref($apiOwner) ne "HeaderDoc::Header") {
  507.                             $pDefineObj->accessControl($cppAccessControlState);
  508.                             $apiOwner->addToVars($pDefineObj);
  509.                         } else { # headers group by type
  510.                             $apiOwner->addToPDefines($pDefineObj);
  511.                         }
  512.                     }                    
  513.                 } ## end inPDefine
  514.                 
  515.                 if ($inEnum) {
  516.                     $enumObj = HeaderDoc::Enum->new;
  517.                     $enumObj->processEnumComment(\@fields);
  518.                      while (($inputLines[$inputCounter] !~ /\w/) && ($inputCounter <= $#inputLines)){ $inputCounter++;print "Input line number: $inputCounter\n" if ($localDebug);};  # move beyond blank lines
  519.                     my  $declaration = $inputLines[$inputCounter];
  520.                     while (($inputLines[$inputCounter] !~ /}/) && ($inputCounter <= $#inputLines)){$declaration .= $inputLines[++$inputCounter];print "Input line number: $inputCounter\n" if ($localDebug);}; # simplistic
  521.                     
  522.                     if (length($declaration)) {
  523.                         $enumObj->declarationInHTML($enumObj->getEnumDeclaration($declaration));
  524. #                     my $s = $enumObj->declaration;
  525. #                     print "Enum dec is:\n";
  526. #                     print "|$s|\n";
  527.                     } else {
  528.                         warn "Couldn't find a declaration for enum near line: $inputCounter\n";
  529.                     }
  530.                     if (length($enumObj->name())) {
  531.                         if (ref($apiOwner) ne "HeaderDoc::Header") {
  532.                             $enumObj->accessControl($cppAccessControlState);
  533.                             $apiOwner->addToVars($enumObj);
  534.                         } else { # headers group by type
  535.                             $apiOwner->addToEnums($enumObj);
  536.                         }
  537.                     }
  538.                 }  ## end inEnum
  539.             }
  540.             $inHeader = $inClass = $inFunction = $inTypedef = $inStruct = $inConstant = $inVar = $inPDefine = $inEnum = 0;
  541.             $inputCounter++;
  542.             print "Input line number: $inputCounter\n" if ($localDebug);
  543.         } # end processing individual line array
  544.         
  545.         if (ref($apiOwner) ne "HeaderDoc::Header") { # if we've been filling a class object, add it to the header
  546.             my $name = $apiOwner->name();
  547.             my $refName = ref($apiOwner);
  548.             $headerObject->addToClasses($apiOwner);
  549.         }
  550.     } # end processing array of line arrays
  551.     $headerObject->createFramesetFile();
  552.     $headerObject->createContentFile();
  553.     $headerObject->createTOCFile();
  554.     $headerObject->writeHeaderElements();
  555.     $headerObject->writeHeaderElementsToCompositePage();
  556.     $headerObject->writeExportsWithName($rootFileName) if (($export) || ($testingExport));
  557. }
  558. print "...done\n";
  559. exit 0;
  560.  
  561.  
  562. #############################  Subroutines ###################################
  563.  
  564. sub getLineArrays {
  565.     my $rawLineArrayRef = shift;
  566.     my @arrayOfLineArrays = ();
  567.     my @generalHeaderLines = ();
  568.     
  569.     my $inputCounter = 0;
  570.     my $lastArrayIndex = @{$rawLineArrayRef};
  571.     my $line = "";
  572.     my $className = "";
  573.     
  574.     while ($inputCounter <= $lastArrayIndex) {
  575.         $line = ${$rawLineArrayRef}[$inputCounter];
  576.         
  577.         # we're entering a headerdoc comment--look ahead for @class tag
  578.         if (($line =~ /^\/\*\!/)) {
  579.             my $headerDocComment = "";
  580.             {
  581.                 local $^W = 0;  # turn off warnings since -w is overly sensitive here
  582.                 while (($line !~ /\*\//) && ($inputCounter <= $lastArrayIndex)) {
  583.                     $line =~ s/^[ \t]*//; # remove leading whitespace
  584.                     $line =~ s/^[*]\s*$/\n/; # replace sole asterisk with paragraph divider
  585.                     $line =~ s/^[*]\s+(.*)/$1/; # remove asterisks that precede text
  586.                     $headerDocComment .= $line;
  587.                     $line = ${$rawLineArrayRef}[++$inputCounter];
  588.                 }
  589.             }
  590.             
  591.             # test for @class comment
  592.             # here is where we create an array of class-specific lines
  593.             # first, get the class name
  594.             if ($headerDocComment =~ /^\/\*!\s+\@class\s*/i) {
  595.                my @classLines;
  596.                
  597.                ($className = $headerDocComment) =~ s/.*\@class\s+(\w+)\s+.*/$1/s;
  598.                push (@classLines, $headerDocComment);
  599.                while (($line !~ /{/) && ($inputCounter <= $lastArrayIndex)) {
  600.                       $line = ${$rawLineArrayRef}[$inputCounter];
  601.                    push (@classLines, $line);
  602.                    $inputCounter++;
  603.                }
  604.                # now we're at the opening brace of the class declaration
  605.                # push it into the array
  606.                $line = ${$rawLineArrayRef}[$inputCounter];
  607.                push (@classLines, $line);
  608.                $inputCounter++;
  609.                
  610.                # now collect class lines until
  611.                my $inClassBraces = 1;
  612.                my $leftBraces;
  613.                my $rightBraces;
  614.                while ($inClassBraces) {
  615.                    $line = ${$rawLineArrayRef}[$inputCounter];
  616.                    push (@classLines, $line);
  617.                    $leftBraces = $line =~ tr/{//;
  618.                    $rightBraces = $line =~ tr/}//;
  619.                    $inClassBraces += $leftBraces;
  620.                    $inClassBraces -= $rightBraces;
  621.                    $inputCounter++;
  622.                }
  623.                 push (@arrayOfLineArrays, \@classLines);
  624.  
  625.             } else {
  626.                 push (@generalHeaderLines, $headerDocComment);
  627.             }
  628.         }
  629.         push (@generalHeaderLines, $line);
  630.         $inputCounter++;
  631.     }
  632.     push (@arrayOfLineArrays, \@generalHeaderLines);
  633.     return @arrayOfLineArrays;
  634. }
  635.  
  636. sub processCPPHeaderComment {
  637. #     for now, we do nothing with this comment
  638.     return;
  639. }
  640.  
  641. sub removeSlashSlashComment {
  642.     my $line = shift;
  643.     $line =~ s/\/\/.*$//;
  644.     return $line;
  645. }
  646.  
  647. sub processClassComment {
  648.     my $apiOwner = shift;
  649.     my $headerObj = $apiOwner;
  650.     my $rootOutputDir = shift;
  651.     my $fieldArrayRef = shift;
  652.     my @fields = @$fieldArrayRef;
  653.     
  654.     $apiOwner = HeaderDoc::CPPClass->new;
  655.     $apiOwner->headerObject($headerObj);
  656.     $apiOwner->outputDir($rootOutputDir);
  657.     foreach my $field (@fields) {
  658.         SWITCH: {
  659.             ($field =~ /^\/\*\!/)&& do {last SWITCH;}; # ignore opening /*!
  660.             ($field =~ s/^class\s+//) && 
  661.             do {
  662.                 my ($name, $disc);
  663.                 ($name, $disc) = &getAPINameAndDisc($field); 
  664.                 $apiOwner->name($name);
  665.                 if (length($disc)) {$apiOwner->discussion($disc);};
  666.                 last SWITCH;
  667.             };
  668.             ($field =~ s/^abstract\s+//) && do {$apiOwner->abstract($field); last SWITCH;};
  669.             ($field =~ s/^discussion\s+//) && do {$apiOwner->discussion($field); last SWITCH;};
  670.             print "Unknown field in class comment: $field\n";
  671.         }
  672.     }
  673.     return $apiOwner;
  674. }
  675.  
  676. sub processHeaderComment {
  677.     my $apiOwner = shift;
  678.     my $rootOutputDir = shift;
  679.     my $fieldArrayRef = shift;
  680.     my @fields = @$fieldArrayRef;
  681.  
  682.     foreach my $field (@fields) {
  683.         # print "header field: |$field|\n";
  684.         SWITCH: {
  685.             ($field =~ /^\/\*\!/)&& do {last SWITCH;}; # ignore opening /*!
  686.             ($field =~ s/^header\s+//) && 
  687.             do {
  688.                 my ($name, $disc);
  689.                 ($name, $disc) = &getAPINameAndDisc($field); 
  690.                 print "Setting header name to $name\n" if ($debugging);
  691.                 print "Discussion is:\n" if ($debugging);
  692.                 print "$disc\n" if ($debugging);
  693.                 if (length($disc)) {$apiOwner->discussion($disc);};
  694.                 last SWITCH;
  695.             };
  696.             ($field =~ s/^abstract\s+//) && do {$apiOwner->abstract($field); last SWITCH;};
  697.             ($field =~ s/^discussion\s+//) && do {$apiOwner->discussion($field); last SWITCH;};
  698.             print "Unknown field in header comment: $field\n";
  699.         }
  700.     }
  701.     return $apiOwner;
  702. }
  703.  
  704. sub printVersionInfo {
  705.     my $av = HeaderDoc::APIOwner->VERSION();
  706.     my $hev = HeaderDoc::HeaderElement->VERSION();
  707.     my $hv = HeaderDoc::Header->VERSION();
  708.     my $cppv = HeaderDoc::CPPClass->VERSION();
  709.     my $fv = HeaderDoc::Function->VERSION();
  710.     my $tv = HeaderDoc::Typedef->VERSION();
  711.     my $sv = HeaderDoc::Struct->VERSION();
  712.     my $cv = HeaderDoc::Constant->VERSION();
  713.     my $vv = HeaderDoc::Var->VERSION();
  714.     my $ev = HeaderDoc::Enum->VERSION();
  715.     my $uv = HeaderDoc::Utilities->VERSION();
  716.     my $me = HeaderDoc::MinorAPIElement->VERSION();
  717.     
  718.     print "----------------------------------------------------\n";
  719.     print "\tHeaderDoc version $VERSION.\n";
  720.     print "\tModules:\n";
  721.     print "\t\tAPIOwner - $av\n";
  722.     print "\t\tHeaderElement - $hev\n";
  723.     print "\t\tHeader - $hv\n";
  724.     print "\t\tCPPClass - $cppv\n";
  725.     print "\t\tFunction - $fv\n";
  726.     print "\t\tTypedef - $tv\n";
  727.     print "\t\tStruct - $sv\n";
  728.     print "\t\tConstant - $cv\n";
  729.     print "\t\tEnum - $ev\n";
  730.     print "\t\tVar - $vv\n";
  731.     print "\t\tMinorAPIElement - $me\n";
  732.     print "\t\tUtilities - $uv\n";
  733.     print "----------------------------------------------------\n";
  734. }
  735.  
  736. ################################################################################
  737. # Version Notes
  738. # 1.61 (02/24/2000) Fixed getLineArrays to respect paragraph breaks in comments that 
  739. #                   have an asterisk before each line.
  740. ################################################################################
  741.  
  742.